#

# LDAP Naming Service Provider for the
Java Naming and Directory InterfaceTM (JNDI)

Please send feedback to jndi@java.sun.com

Table of Contents

1. Introduction
2. Conformance
3. Environment Properties
4. Names
5. Attributes
6. URLs
7. Java Objects
8. Schema
9. Exceptions
10. API Mapping
11. Federation
12. Event Notification
13. SASL Authentication
14. SSL and Start TLS
15. Security Considerations

## 1. Introduction

The Lightweight Directory Access Protocol (LDAP) is an Internet standard for accessing directory services. The JNDI/LDAP service provider provides access to servers implementing the LDAP protocols.

This document describes the features of the LDAP service provider. A major portion of the description is couched in terms of how the LDAP service provider behaves with respect to the descriptions in Guidelines for LDAP Service Providers. For examples and descriptions of how to use this provider, please see the JNDI Tutorial.

The LDAP service provider implements the basic features for LDAP access. Additional functionality, such as support for a number of popular LDAP controls, and for storing and reading RMI and CORBA objects, can be added to the basic provider by installing a booster pack, available for download at the JNDI Web site.

## 2. Conformance

The LDAP service provider conforms to the following standards:

Standard | Supported | Comments
--- | --- | ---
LDAPv3 (RFC 2251) | Yes |
LDAPv3 Attributes (RFC 2252) | Yes |
LDAPv3 Distinguished Names (RFC 2253) | Yes |
LDAP Search Filters (RFC 2254) | Yes |
LDAP URL Format (RFC 2255) | Yes |
LDAPv3 Schema (RFC 2256) | Yes |
LDAPv2 (RFC 1777) | Yes |
LDAP Authentication (RFC 2829) | Yes |
Start TLS Extension (RFC 2830) | Yes |
DIGEST-MD5 (RFC 2831) | Yes |

## 3. Environment Properties

Descriptions of JNDI, LDAP-specific, and SASL-specific properties are found in Guidelines for LDAP Service Providers.

### 3.1 JNDI Properties

The LDAP service provider supports the following JNDI environment properties:

Property | Supported | Comments
--- | --- | ---
`java.naming.batchsize` | Yes | Default value is `1`.
`java.naming.factory.control` | Yes | ``
`java.naming.factory.initial` | Yes | Specify `com.sun.jndi.ldap.LdapCtxFactory` to use the LDAP service provider as the initial context.
`java.naming.factory.object` | Yes |
`java.naming.factory.state` | Yes |
`java.naming.language` | No | Ignored by the provider.
`java.naming.provider.url` | Yes |
`java.naming.referral` | Yes |
`java.naming.security.authentication` | Yes | `simple`, `none`, list of SASL mechanisms
`java.naming.security.credentials` | Yes |
`java.naming.security.principal` | Yes |
`java.naming.security.protocol` | Yes | `ssl`

### 3.2 LDAP-specific Properties

The provider supports the following LDAP-specific environment properties:

Property | Supported | Comments
--- | --- | ---
`java.naming.ldap.attributes.binary` | Yes |
`java.naming.ldap.control.connect` | Yes |
`java.naming.ldap.deleteRDN` | Yes |
`java.naming.ldap.derefAliases` | Yes |
`java.naming.ldap.factory.socket` | Yes | Default value is `javax.net.ssl.SSLSocketFactory` when the `java.naming.security.protocol` property is set to `ssl`. See the SSL Section for details.
`java.naming.ldap.ref.separator` | Yes |
`java.naming.ldap.referral.limit` | Yes |
`java.naming.ldap.typesOnly` | Yes |
`java.naming.ldap.version` | Yes |

### 3.3 SASL-specific Properties

The provider supports the following SASL-specific environment properties:

Property | Supported | Comments
--- | --- | ---
`java.naming.security.sasl.authorizationId` | Yes |
`java.naming.security.sasl.callback` | Yes |
`java.naming.security.sasl.realm` | Yes |
`javax.security.sasl.client.pkgs` | Yes |
`javax.security.sasl.qop` | Yes |
`javax.security.sasl.strength` | Yes | Cipher selected depends on the ciphers available from the Java Cryptography Extension (JCE) service providers in the Java platform.
`javax.security.sasl.maxbuffer` | Yes |
`javax.security.sasl.server.authentication` | Yes |
`javax.security.sasl.policy.forward` | Yes |
`javax.security.sasl.policy.credentials` | Yes |
`javax.security.sasl.policy.noplaintext` | Yes |
`javax.security.sasl.policy.noactive` | Yes |
`javax.security.sasl.policy.nodictionary` | Yes |
`javax.security.sasl.policy.noanonymous` | Yes |

### 3.4 Provider-specific Properties

The LDAP service provider defines the following provider-specific environment properties:
`com.sun.jndi.ldap.connect.timeout`

> The value of this property is the string representation of an integer representing the connection timeout in milliseconds. If the LDAP provider cannot establish a connection within that period, it aborts the connection attempt. The integer should be greater than zero. An integer less than or equal to zero means to use the network protocol's (i.e., TCP's) timeout value.

> If this property is not specified, the default is to wait for the connection to be established or until the underlying network times out.

> For example,

> > `env.put("com.sun.jndi.ldap.connect.timeout", "500");`

> causes the LDAP service provider to abort the connection attempt if a connection cannot be established in half a second.

> NOTE: On systems earlier than the Java 2 SDK, v 1.4, this property is ignored because there is no support in the SDK for connection timeouts.

`com.sun.jndi.ldap.netscape.schemaBugs`

> The Netscape Directory Server 4.0 and earlier releases do not support schema entries that comply with RFC 2252. Specifically, contrary to RFC 2252, the Netscape server requires OIDs (such as those for SUP and SYNTAX) be delimited by single quotes and MUST/MAY lists be enclosed by parentheses. When you update the schema of the Netscape Directory Server 4.0, you need to use this property to get around these problems.

> The following values are defined for this property:

> `true`
> activate the workaround.
> `false`
> do not activate the workaround.

> If this property is not set then its default value is `false`.

> For example,

> >     env.put("com.sun.jndi.ldap.netscape.schemaBugs", "true");

> activates the workaround.

> NOTE 1: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the `addToEnvironment` or `removeFromEnvironment` methods.

> NOTE 2: If you are using Netscape Directory Server 4.1, do not use this property. The 4.1 server has problems parsing object class definitions that contain MUST/MAY clauses without parentheses. If you are creating or modifying an object class definition that contains a single MUST/MAY item, work around the bug by adding a superfluous value (such as 'objectClass') to the MUST/MAY list.

`com.sun.jndi.ldap.trace.ber`

> The value of this property is a `java.io.OutputStream` object into which a hexadecimal dump of the incoming and outgoing LDAP ASN.1 BER packets is written.

> No default is defined for this property.

> For example,

> > `env.put("com.sun.jndi.ldap.trace.ber", System.out);`

> directs the LDAP protocol trace to the standard output stream.

> NOTE: This property may only be passed to the initial context and becomes fixed for the provider. It is unaffected by the `addToEnvironment` or `removeFromEnvironment` methods.

## 4. Names

The LDAP service provider supports names in accordance with the description in Guidelines for LDAP Service Providers. It supports LDAP distinguished names in the following formats:

Distinguished Name format | Comments
--- | ---
`String` | Treat as composite name. Process the first component of the composite name as a distinguished name. Use rest of the components for federation.
`Name` | If instance of `CompositeName`, treat as composite name, which means process the first component of the composite name as a distinguished name and use the rest for federation. Otherwise, treat as parsed LDAP name, where each component of `Name` is a component of the LDAP name as defined in RFC 2253.
LDAP URL String | When passed to the initial context, the LDAP URL string is interpreted according to RFC 2255, and its distinguished name component interpreted according to RFC 2253.

The name parser returned by an invocation of `getNameParser()` returns a parser that, when given a string name, parses it into components in accordance with RFC 2253.

## 5. Attributes

The LDAP service provider supports attributes in accordance with the description in Guidelines for LDAP Service Providers. It supports the following formats for specifying LDAP attribute values:

Attribute value format | Supported | Comments
--- | --- | ---
`String` values | Yes |
`byte[]` values | Yes |

Some LDAP servers support attribute subtyping, attribute name synonyms, and language codes for specifying language preferences for attribute values. In such cases, the attribute name returned by an LDAP server may be different from the one which was requested.

In LDAP, attribute names are case-insensitive. Therefore, when creating a collection of attributes to be passed as a parameter to JNDI operations, it is recommended to use a case-insensitive attributes class. For example,

`Attributes attrs = new BasicAttributes(true); // ignoreCase=true`

For all attribute values, regardless of whether they are `String` or `byte[]`, you need to know the syntax and format of the attribute value. You can typically find this out by reading the schema document in which the attribute and its syntax is defined.

When attributes are supplied as arguments to JNDI calls then they must satisfy whatever schema is enforced at the LDAP directory. In particular, the `objectClass` attribute is normally required when creating a new LDAP entry (for example, when using Context.bind, Context.rebind or DirContext.createSubcontext).

## 6. URLs

The LDAP service provider supports URLs in accordance with the description in Guidelines for LDAP Service Providers. It supports the following use of URLs:

URL usage | Supported | Comments
--- | --- | ---
LDAP URLs to configure the LDAP service provider. | Yes |
URLs passed as names to the `InitialDirContext` methods. | Yes | The attributes, scope, filter and extensions components of LDAP URLs are ignored by the `search` methods.
URLs in LDAP referrals | Yes | The scope component of LDAP URLs is supported. The attributes, filter and extensions components are ignored.
URLs returned as names in `list`, `listBindings`, and `search` enumerations. | Yes |
URLs linking federated namespaces. | Yes |

## 7. Java Objects

The LDAP service provider supports storing and reading the following types of objects, as specified in Guidelines for LDAP Service Providers.

Storable/Readable Objects | Supported | Comments
--- | --- | ---
`Reference` objects | Yes |
`Referenceable` objects | Yes |
`Serializable` objects | Yes |
`DirContext` objects | Yes |

See the JNDI Tutorial for examples.

## 8. Schema

The LDAP service provider supports the following schema bindings, as specified in Guidelines for LDAP Service Providers.

Schema Tree | Supported | Comments
--- | --- | ---
AttributeDefinition | Yes |
ClassDefinition | Yes |
SyntaxDefinition | Yes |
MatchingRule | Yes |
ExtensionDefinition | No |
ControlDefinition | No |
SASLMechanism | No |

## 9. Exceptions

The LDAP service provider maps LDAP error codes to JNDI exceptions according to Guidelines for LDAP Service Providers.

## 10. API Mapping

The LDAP service provider maps the following JNDI API methods to LDAP according to Guidelines for LDAP Service Providers:

Mapping for `Context` methods | Supported | Comments
--- | --- | ---
`addToEnvironment` | Yes |
`bind` | Yes |
`close` | Yes |
`composeName` | Yes |
`destroySubcontext` | Yes |
`getEnvironment` | Yes |
`getNameInNamespace` | Yes |
`getNameParser` | Yes |
`list` | Yes |
`listBindings` | Yes |
`lookup` | Yes | Does not process `LinkRef` specially.
`lookupLink` | Yes |
`rebind` | Yes |
`removeFromEnvironment` | Yes |
`rename` | Yes |
`unbind` | Yes |

Mapping for `DirContext` methods | Supported | Comments
--- | --- | ---
`bind` | Yes |
`createSubcontext` | Yes |
`destroySubcontext` | Yes |
`getAttributes` | Yes |
`getSchema` | Yes |
`getSchemaClassDefinition` | Yes |
`modifyAttributes` | Yes |
`rebind` | Yes |
`search` | Yes |

Mapping for `LdapContext` methods | Supported | Comments
--- | --- | ---
`extendedOperation` | Yes |
`getRequestControls` | Yes |
`getResponseControls` | Yes |
`newInstance` | Yes |
`reconnect` | Yes |
`setRequestControls` | Yes |

Mapping for `EventDirContext` methods | Supported | Comments
--- | --- | ---
`addNamingListener` | Yes |
`removeNamingListener` | Yes |
`targetMustExist` | Yes |

## 11. Federation

The LDAP service provider supports federation in accordance with the description in Guidelines for LDAP Service Providers. It supports the following federation techniques:

Federation Technique | Supported | Comments
--- | --- | ---
Junction | Yes | Except when subordinate naming system is another LDAP system
Implicit Next Naming System Pointer | Yes |

The LDAP service provider treats composite names as strongly separated. That is, it processes the first component of the composite name as a distinguished name and the rest of the components as names in the next naming system(s). For example, here are examples that lists the root of the next naming system federated beyond an LDAP context and looks up a name using a multicomponent composite name:

>     // List the root of the nns,
>     // Note use of the trailing slash to indicate traversal into the nns
>     NamingEnumeration enum = ctx.list("cn=objects,ou=Sales/");

>     // A composite name lookup
>     Object obj = ctx.lookup("cn=objects,ou=Sales/some/x/y/z");

## 12. Event Notification

The LDAP service provider supports event notification in accordance with the description in Guidelines for LDAP Service Providers. It supports the following events:

Event | Supported | Comments
--- | --- | ---
Namespace change notification | Yes | Uses the persistent search control*
Object change notification | Yes | Uses the persistent search control*
Unsolicited notification | Yes |

* The persistent search control is defined in the IETF Internet-Draft `draft-ietf-ldapext-psearch-03.txt`.

## 13. SASL Authentication

The LDAP service provider supports SASL authentication in accordance with the description in Guidelines for LDAP Service Providers.

The LDAP service provider supports the following SASL mechanisms.

- EXTERNAL (RFC 2222). This mechanism obtains authentication information from an external source (such as SSL/TLS or IPsec).
- DIGEST-MD5 (RFC 2831) is for Digest Authentication.
- GSSAPI (RFC 2222) is for Kerberos V5 authentication.

In addition to these mechanisms, the provider supports additional SASL mechanisms made available via the framework defined in the Java SASL API (JSR 28 Public Review Draft), with the exception that the package is named `com.sun.security.sasl.preview` instead of `javax.security.sasl`.

## 14. SSL and Start TLS

The LDAP service provider supports SSL in accordance with the description in Guidelines for LDAP Service Providers. It uses the default socket factory `javax.net.ssl.SSLSocketFactory` unless the `java.naming.ldap.factory.socket` property has been set to the class name of some other socket factory.

The LDAP provider supports the the "Start TLS" extension ("1.3.6.1.4.1.1466.20037") by supplying a concrete implementation of the `StartTlsResponse` abstract class.

## 15. Security Considerations

When a security manager has been installed, you must grant to the application using JNDI and the LDAP service provider the following permissions:

    permission java.net.SocketPermission "host[:port]", "connect";

> For each host/port identified in the `java.naming.factory.initial` property and in URL string names supplied to context methods.

    permission java.net.SocketPermission "host[:port]", "connect,accept";

> For each host/port named in the URL strings in `References` and `javaCodebase` attributes stored with `Serializable` objects.

If you are using SASL authentication and will be setting the SASL client factory programmatically, grant your application the following permission.

    permission java.lang.RuntimePermission "setFactory"

If you use the "GSSAPI" SASL mechanism, you need the following additional permissions.

    permission javax.security.auth.AuthPermission "createLoginContext.appClassName";
    permission javax.security.auth.AuthPermission "doAsPrivileged";

> For the application class that's going to be logging in and invoking the `doAsPrivileged` method.

    permission java.net.SocketPermission "host[:port]", "connect";

> For the host/port of the Kerberos Key Distribution Center (KDC).

    permission javax.security.auth.kerberos.ServicePermission "krbtgt/realm@realm", "initiate";
    permission javax.security.auth.kerberos.ServicePermission "ldap/fully-qualified-hostname@realm", "initiate";

> For the realm and host of the LDAP service and KDC.

Copyright © 1999-2001 Sun Microsystems, Inc., All Rights Reserved.